From 6cd8ec5f78ca2eaa09f27aa33aa3a33309cc374b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 11 Jul 2007 04:46:03 +0000 Subject: [PATCH] More tooltips docs svn path=/trunk/; revision=18443 --- docs/reference/ChangeLog | 13 ++++ docs/reference/gtk/Makefile.am | 2 + docs/reference/gtk/gtk-docs.sgml | 5 +- docs/reference/gtk/migrating-GtkTooltip.sgml | 62 +++++++++++++++++++ docs/reference/gtk/tmpl/gtktooltip.sgml | 65 ++++++++++++++++++-- 5 files changed, 140 insertions(+), 7 deletions(-) create mode 100644 docs/reference/gtk/migrating-GtkTooltip.sgml diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index cb66d48896..0b26c720ee 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,16 @@ +2007-07-11 Matthias Clasen + + * gtk/migrating-GtkTooltip.sgml: Migration chapter + for tooltips. + + * gtk/gtk-docs.sgml: Include it, and move GtkTooltips + chapter to "Deprecated". + + * gtk/Makefile.am: Glue + + * gtk/tmpl/gtktooltip.sgml: Add more content from + Kris' "tooltips in 5 minutes" mail. + 2007-07-10 Matthias Clasen * gdk/tmpl/colors.sgml: Remov references to deprecated diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index f596d8a88a..f123be2f68 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -136,6 +136,7 @@ content_files = \ migrating-GtkRecentChooser.sgml \ migrating-GtkLinkButton.sgml \ migrating-GtkBuilder.sgml \ + migrating-GtkTooltip.sgml \ objects_grouped.sgml \ osx.sgml \ question_index.sgml \ @@ -162,6 +163,7 @@ expand_content_files = \ migrating-GtkRecentChooser.sgml \ migrating-GtkLinkButton.sgml \ migrating-GtkBuilder.sgml \ + migrating-GtkTooltip.sgml \ tree_widget.sgml \ text_widget.sgml \ question_index.sgml diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 5f720b6c18..c1667a3ae6 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -226,6 +226,7 @@ + @@ -545,7 +546,6 @@ that is, GUI components such as #GtkButton or #GtkTextView. &GtkIMMulticontext; &GtkSizeGroup; &GtkTooltip; - &GtkTooltips; &GtkViewport; &GtkAccessible; @@ -614,6 +614,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. &GtkPreview; &GtkProgress; &GtkText; + &GtkTooltips; &GtkTipsQuery; &GtkTree; &GtkTreeItem; @@ -646,6 +647,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. >k-migrating-GtkRecentChooser; >k-migrating-GtkLinkButton; >k-migrating-GtkBuilder; + >k-migrating-GtkTooltip; @@ -682,4 +684,5 @@ that is, GUI components such as #GtkButton or #GtkTextView. Index of new symbols in 2.12 + diff --git a/docs/reference/gtk/migrating-GtkTooltip.sgml b/docs/reference/gtk/migrating-GtkTooltip.sgml new file mode 100644 index 0000000000..f0fc971bb8 --- /dev/null +++ b/docs/reference/gtk/migrating-GtkTooltip.sgml @@ -0,0 +1,62 @@ + + + Migrating from GtkTooltips to GtkTooltip + + + GTK+ 2.12 brings a completely new tooltip implementation which + allows many things that were not possible with the old + #GtkTooltips interface. The new possibilities are explained + in more detail in the section about #GtkTooltip. + + + + A number of complications of the old API have been removed: + + + + Tooltips can not be grouped anymore. The old tooltips + API allowed this by using multiple #GtkTooltips objects. + We believe that the timeout behaviour of the new tooltips + implementation is better and makes it unnecessary to use + grouping as a way to overcome shortcomings of the + fast-tooltips mode. + + + + Timeouts can not be set individually anymore. Instead + there are settings #GtkSettings:gtk-tooltip-timeout, + #GtkSettings:gtk-tooltip-browse-timeout and + #GtkSettings:gtk-tooltip-browse-mode-timeout to influence + the behaviour of tooltips globally. + + + + + + + Here is an example of setting a tooltip on a widget with the old API: + +GtkTooltips *tooltips = gtk_tooltips_new (); +gtk_tooltips_set_tip (tooltips, widget, "Some tips", NULL); + + + + Using the new tooltips API, it is no longer necessary to create + an object: + +gtk_widget_set_tooltip_text (widget, "Some tips"); + + + + Similarly, setting a tooltip on a #GtkToolItem gets + simplified from + +gtk_tool_item_set_tooltip (toolitem, toolbar->tooltips, "tool tip", NULL); + + to + +gtk_tool_item_set_tooltip_text (toolitem, text); + + + + diff --git a/docs/reference/gtk/tmpl/gtktooltip.sgml b/docs/reference/gtk/tmpl/gtktooltip.sgml index 15a00ccc3f..1d18d66c7e 100644 --- a/docs/reference/gtk/tmpl/gtktooltip.sgml +++ b/docs/reference/gtk/tmpl/gtktooltip.sgml @@ -11,14 +11,67 @@ introduced in GTK+ 2.12 and which deprecates the old #GtkTooltips API. -Basic tooltips can be realized simply by using -gtk_widget_set_tooltip_text() or gtk_widget_set_tooltip_markup() without -any explicit tooltip object. For fancy tooltips, you will likely -connect to the #GtkWidget::query-tooltip signal, which is passed -a #GtkTooltip object as the last parameter. You can use functions -like gtk_tooltip_set_icon() to modify the tooltip. +Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text() +or gtk_widget_set_tooltip_markup() without any explicit tooltip object. + +When you need a tooltip with a little more fancy contents, like +adding an image, or you want the tooltip to have different contents +per GtkTreeView row or cell, you will have to do a little more work: + + + +Set the #GtkWidget:has-tooltip property to %TRUE, this will +make GTK+ monitor the widget for motion and related events +which are needed to determine when and where to show a tooltip. + + + +Connect to the #GtkWidget::query-tooltip signal. This signal +will be emitted when a tooltip is supposed to be shown. One +of the arguments passed to the signal handler is a #GtkTooltip +object. This is the object that we are about to display as a +tooltip, and can be manipulated in your callback using functions +like gtk_tooltip_set_icon(). There are functions for setting +the tooltip's markup, setting an image from a stock icon, or +even putting in a custom widget. + + + +Return %TRUE from your query-tooltip handler. This causes +the tooltip to be show. If you return %FALSE, it will not be shown. + + + + + +In the probably rare case where you want to have even more control +over the tooltip that is about to be shown, you can set your own +#GtkWindow which will be used as tooltip window. This works as +follows: + + + +Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as +before. + + + +Use gtk_widget_set_tooltip_window() to set a #GtkWindow created +by you as tooltip window. + + + +In the ::query-tooltip callback you can access your window +using gtk_widget_get_tooltip_window() and manipulate as you +wish. The semantics of the return value are exactly as before, +return %TRUE to show the window, %FALSE to not show it. + + + + + -- 2.30.2